EnigmA Amiga Run 1995 October

home *** CD-ROM | disk | FTP | other *** search

/ EnigmA Amiga Run 1995 October / EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso / Aminet / comm / tcp / ATCP_sdk_40_gc.lha / AmiTCP-4.0-gcc / doc / usergroup.doc < prev

Wrap

Text File | 1994-10-15 | 45KB | 1,321 lines

TABLE OF CONTENTS usergroup.library/--background-- usergroup.library/--Licence-- usergroup.library/crypt usergroup.library/getcredentials usergroup.library/getgrent usergroup.library/getgroups usergroup.library/getlastlog usergroup.library/getlogin usergroup.library/getpass usergroup.library/getpwent usergroup.library/getspgrp usergroup.library/getuid usergroup.library/getumask usergroup.library/getutent usergroup.library/initgroups usergroup.library/MU2UG usergroup.library/setgroups usergroup.library/setlastlog usergroup.library/setlogin usergroup.library/setsid usergroup.library/setuid usergroup.library/ug_GetConsoleName usergroup.library/ug_GetErr usergroup.library/ug_GetSalt usergroup.library/ug_OnConsole usergroup.library/ug_SetupContextTags usergroup.library/ug_StrError usergroup.library/umask usergroup.library/--background-- usergroup.library/--background-- WARNING Unfortunately, this experimental release of usergroup.library is not compatible with multiuser.library. There are some problems with multiuser.library, eg. the multiuser.library does not support the real ids. Also the password format is different, multiuser.library uses the AS225r2 password format, which is very simple encoding. The usergroup.library uses the standard Unix password encryption. The current implementation of this model is very simple. All tasks belong to one session and they share common credentials. The setsid() function call does nothing. You are supposed to log in using "login -f login-name" when the machine is booted. PURPOSE When the AmiTCP/IP was originally released, a little attention was paid to the security aspects. Since the AmigaOS is basically a single user operating system with little or no provisions for multiple users, there was no standard how accounts, password checking and access control should be implemented. USERGROUP.LIBRARAY SEMANTICS The usergroup.library provides a BSD-stylish interface to the user and group identification, the account database, the group databases, password checking and login information. Since it is a shared library instead of link library, the underlying security mechanisms can be changed according future standards and needs. The usergroup.library provides quite clean basic model. Each process has credentials, which consist of real used ID, real group ID, effective user ID and up to 32 effective group IDs. The process credentials can be changed with setuid()/setgid()/setgroups() functions. Each process belongs also to an session. A new session will created with setsid() function call, which is typically executed before you call command or when you create a new connection. A session contains the login name of the user and possibly some other information. The information about users logging in and out is typically stored into a file in Unix systems. These files (in BSD Net2 release they are /var/run/utmp and /var/log/wtmp) are usually very long and contain holes. Since the AmigaDOS files cannot contain holes, this approach is not practical. The usergroup.library provides an loosely HP-UX-stylish interface to the utmp and lastlogin databases. The utmp database contains an entry for each session, it is searched in linear manner qith getutent(). The lastlogin database contains an entry for each user and getlastlogin() returns an entry for given UID. The usergroup.library does not directly depend on AmiTCP/IP. It can be used with any program needing user identification, account and group databases. USING USERGROUP.LIBRARY Each time the usergroup.library is opened, it creates an new instance of the library base. The library base contains the static data buffers used by many library functions. The usergroup.library functions behave exactly like they were in link library. The functions allocate all resources for you, the library also frees the resources when they are no more needed. Since each library contains static data and resources allocated in the context of calling task (ie. signals), only the task which opened the library is allowed to call most library functions. However, any task whatsoever can call following functions: getuid() geteuid() getgid() getegid() getsid() These functions return the credentials of calling task. It is also possible to call following functions from any task. However, note that a non-owning tasks cannot recover error codes: getgroups() setreuid() setuid() setregid() setgid() setgroups() setsid() setlogin() It is possible to give the library instance to another task. Only the current owner can close the library. The user and group information is provided by netinfo.device. It is more convenient interface to user and group databases for multitasking applications. EXAMPLE PROGRAMS There are a few utilities provided as examples. The finger programs deals with user (password), utmp and lastlog database, the id and whoami with user and group identification, login and passwd with password checking and password changing. SEE ALSO netinfo.device/--background--, ug_SetupContextTags(), SAS C Manual, libinit.c and libinitr.o COPYRIGHT Copyright © 1980--1991 The Regents of the University of California. Copyright © 1993, 1994 AmiTCP/IP Group, Network Solutions Development Inc., Finland. usergroup.library/--Licence-- usergroup.library/--Licence-- USERGROUP.LIBRARY LICENCE The usergroup.library is Copyright © 1993, 1994 AmiTCP/IP Group, Network Solutions Development Inc., Finland. The usergroup.library contains source code from 4.3BSD Net2 release. The 4.3BSD Net2 release is copyright © 1980 --- 1991 The Regents of the University of California. The following licence apply to the usergroup.library and its documentation: Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgement: This product includes software developed by the University of California, Berkeley and its contributors. 4. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. usergroup.library/crypt usergroup.library/crypt NAME crypt - password encryption with DES SYNOPSIS result = crypt(key, setting); D0 A0 A1 char *crypt(const char *, const char *) FUNCTION The crypt function performs password encryption. It is derived from the NBS Data Encryption Standard. Additional code has been added to deter key search attempts. INPUTS key - a NUL-terminated string (normally a password typed by a user). setting - a character array, 9 bytes in length, consisting of an underscore (`_') followed by 4 bytes of iteration count and 4 bytes of salt. Both the iteration count and the salt are encoded with 6 bits per character, least significant bits first. The values 0 to 63 are encoded by the characters `./0-9A-Za-z', respectively. The salt is used to induce disorder in to the DES algorithm in one of 16777216 possible ways (specifically, if bit i of the salt is set then bits i and i+24 are swapped in the DES `E' box output). The key is divided into groups of 8 characters (a short final group is null-padded) and the low-order 7 bits of each each character (56 bits per group) are used to form the DES key as follows: the first group of 56 bits becomes the initial DES key. For each additional group, the XOR of the group bits and the encryption of the DES key with itself becomes the next DES key. Then the final DES key is used to perform count cumulative encryptions of a 64-bit constant. RESULTS result - a NUL-terminated string, 20 bytes in length, consisting of the setting followed by the encoded 64-bit encryption. NOTE For compatibility with Version 7 UNIX version of crypt(), the setting may consist of 2 bytes of salt, encoded as above, in which case an iteration count of 25 is used, fewer perturbations of DES are available, at most 8 characters of key are used, and the returned value is a NUL-terminated string 13 bytes in length. HISTORY A rotor-based crypt() function appeared in Version 6 AT&T UNIX. The current style crypt() first appeared in Version 7 AT&T UNIX. BUGS The crypt() function leaves its result in an internal static object and returns a pointer to that object. Subsequent calls to crypt() will modify the same object. SEE ALSO netutil/login, netutil/passwd, getpass(), netinfo.device/passwd Wayne Patterson, Mathematical Cryptology for Computer Scientists and Mathematicians, ISBN 0-8476-7438-X, 1987. R. Morris, and Ken Thompson, "Password Security: A Case History", Communications of the ACM, vol. 22, pp. 594-597, Nov. 1979. M.E. Hellman, "DES will be Totally Insecure within Ten Years", IEEE Spectrum, vol. 16, pp. 32-39, July 1979. usergroup.library/getcredentials usergroup.library/getcredentials NAME getcredentials -- get credentials of given task. (V4) SYNOPSIS #include <libraries/usergroup.h> credentials = getcredentials(task) D0 A0 struct UserGroupCredentials *getcredentials(struct Task *); FUNCTION The function getcredentials() returns all credentials of the given task. The credentials include real and effective user and group IDs, umask, login name and session ID. If the task pointer is NULL, the credentials of current task are returned. RESULT A getcredentials() function returns a valid pointer to structure UserGroupCredentials on success and a null pointer if an error occurs. ERRORS [EINVAL] An illegal task pointer was specified. BUGS This function leave its result in an internal static object and return a pointer to that object. Subsequent calls to this function will modify the same object. SEE ALSO usergroup.library/getgrent usergroup.library/getgrent NAME getgrgid, getgrnam, getgrent, setgrent, endgrent - group database operations SYNOPSIS #include <grp.h> groupent = getgrgid(gid) D0 D0 struct group *getgrgid(gid_t); groupent = getgrnam(name) D0 A1 struct group *getgrnam(const char *); groupent = getgrent() D0 struct group *getgrent(void); setgrent() void setgrent(void); endgrent() void endgrent(void); FUNCTION These functions operate on the group database via netinfo.device interface. They provide a convenient unix-compatible interface to the group unit of the netinfo.device. The local group database is stored in the file AmiTCP:db/group, its format is described in netinfo.device/group. The entry returned by each reading function is defined by the structure group found in the include file <grp.h>: struct group { char *gr_name; /* Group name. */ char *gr_passwd; /* Password. */ gid_t gr_gid; /* Group ID. */ char **gr_mem; /* Member list. */ }; The functions getgrnam() and getgrgid() search the group database for the given group name pointed to by name or the group id pointed to by gid, respectively, returning the first one encountered. Identical group names or group gids may result in undefined behavior. The getgrent() function sequentially reads the group database and is intended for programs that wish to step through the complete list of groups. All three routines will open the group unit of netinfo.device for reading, if necesssary. The setgrent() function opens the group unit of netinfo.device. The endgrent() function closes the group unit of netinfo.device. It is recommended to call endgrent() if the program won't access group database any more. RESULTS The functions getgrent(), getgrnam(), and getgrgid(), return a pointer to the group entry if successful; if the end of database is reached or an error occurs a null pointer is returned. The functions endgrent() and setgrent() have no return value. ERRORS [ENOENT] -- the netinfo.device could not be opened. Other netinfo.device IO errors can be retrieved by ug_GetErr(). FILES AmiTCP:db/group The group database file SEE ALSO getpwnam(), netinfo.device/group HISTORY The functions getgrgid(), getgrnam(), getgrent(), setgrent() and endgrent() appeared in Version 7 AT&T UNIX. BUGS These functions leave their results in an internal static object and return a pointer to that object. Subsequent calls to the same function will modify the same object. If you need re-entrant operation, you can use directly the netinfo.device commands. COMPATIBILITY The BSD passwd database handling routines setgrfile() and setgroupent() are fairly useless in a networked environment and they are not implemented. usergroup.library/getgroups usergroup.library/getgroups NAME getgroups - get group access list SYNOPSIS len = getgroups(gidsetlen, gidset[]) D0 D0 A0 int getgroups(int, gid_t *); FUNCTION Getgroups() gets the current group access list of the user process and stores it in the array gidset. The parameter gidsetlen indicates the number of entries that may be placed in gidset. The function getgroups() returns the actual number of groups returned in gidset. No more than NGROUPS, as defined in <libraries/usergroup.h>, will ever be returned. RESULT A successful call returns the number of groups in the group set. A value of -1 indicates that the argument gidsetlen is smaller than the number of groups in the group set. ERRORS [EINVAL] The argument gidsetlen is smaller than the number of groups in the group set. [EFAULT] The argument gidset specifies an invalid address. SEE ALSO setgroups(), initgroups(), getgid(), getegid() HISTORY The getgroups function call appeared in 4.2BSD. usergroup.library/getlastlog usergroup.library/getlastlog NAME getlastlog - get lastlog database entry SYNOPSIS #include <utmp.h> lastlog = getlastlog(uid) D0 D0 struct lastlog *getlastlog(uid_t); FUNCTION The getlastlog() function search the lastlog database for the given user id. There should be an lastlog entry for each user. A lastlog entry with ll_time being zero means that user has never logged in this system. The entry returned by getlastlog is defined by the structure lastlog found in the include file <utmp.h>: struct lastlog { long ll_time; /* the login time */ uid_t ll_uid; /* user ID */ char ll_name[UT_NAMESIZE]; /* the login name */ char ll_line[UT_LINESIZE]; /* the name of login device */ char ll_host[UT_HOSTSIZE]; /* where the login originated */ }; RESULTS The function getlastlog() returns a pointer to the lastlog entry if successful; if an error occurs a null pointer is returned. ERRORS [ENOENT] -- no lastlog entry was found [EINVAL] -- the user ID was illegal SEE ALSO setlastlog() BUGS The getlastlog() function leaves its result in an internal static object and return a pointer to that object. Subsequent calls to the same function will modify the same object. Current implementation stores only the lastlog data of the latest user logged in. usergroup.library/getlogin usergroup.library/getlogin NAME getlogin - get login name SYNOPSIS name = getlogin() D0 char *getlogin(void) FUNCTION The getlogin() routine returns the login name of the user associated with the current session, as previously set by setlogin(). The name is normally associated with a console at the time a session is created, and is inherited by all processes descended from the login process. (This is true even if some of those processes assume another user ID, for example when su is used.) INPUTS RESULT name - pointer to login name SEE ALSO setlogin() usergroup.library/getpass usergroup.library/getpass NAME getpass - get a password SYNOPSIS password = getpass(prompt) D0 A1 char *getpass(const char *); FUNCTION The getpass() function displays a prompt to, and reads in a password from "CONSOLE:". If this device is not accessible, getpass() displays the prompt on the standard error output and reads from the standard input. The password may be up to _PASSWORD_LEN (currently 128) characters in length. Any additional characters and the terminating newline character are discarded. Getpass turns off character echoing while reading the password. RESULT password - a pointer to the null terminated password FILES Special device "CONSOLE:" SEE ALSO crypt() HISTORY A getpass function appeared in Version 7 AT&T UNIX. BUGS The getpass function leaves its result in an internal static object and returns a pointer to that object. Subsequent calls to getpass will modify the same object. The calling program should zero the password as soon as possible to avoid leaving the cleartext password visible in the memory. usergroup.library/getpwent usergroup.library/getpwent NAME getpwent, getpwnam, getpwuid, setpwent, endpwent - password database operations SYNOPSIS #include <pwd.h> pw = getpwuid(uid) D0 D0 struct passwd *getpwuid(uid_t); pw = getpwnam(name) D0 A1 struct passwd *getpwnam(const char *); pw = getpwent() D0 struct passwd *getpwent(void); setpwent() void setpwent(void); endpwent() void endpwent(void); FUNCTION These functions operate on the user database via netinfo.device interface. They provide convenient unix-compatible interface to the password unit of the netinfo.device. The local password database is stored in the file AmiTCP:db/passwd, its format is described in netinfo.device/passwd. The entry returned by each reading function is defined by the structure passwd found in the include file <pwd.h>: struct passwd { char *pw_name; /* Username */ char *pw_passwd; /* Encrypted password */ pid_t pw_uid; /* User ID */ gid_t pw_gid; /* Group ID */ char *pw_gecos; /* Real name etc */ char *pw_dir; /* Home directory */ char *pw_shell; /* Shell */ }; The functions getpwnam() and getpwuid() search the password database for the given login name or user uid, respectively, always returning the first one encountered. The getpwent() function sequentially reads the password database and is intended for programs that wish to process the complete list of users. All three routines will open the password unit of netinfo.device for reading, if necesssary. The setpwent() function opens the password unit of netinfo.device. The endpwent() function closes the password unit of netinfo.device. It is recommended to call endpwent() if the program won't access password database any more. RESULTS The functions getpwent(), getpwnam() and getpwuid() return a valid pointer to a passwd structure on success and a null pointer if end of database is reached or an error occurs. The functions endpwent() and setpwent() have no return value. ERRORS [ENOENT] -- the netinfo.device could not be opened. Other netinfo.device IO errors can be retrieved by ug_GetErr(). FILES AmiTCP:db/passwd The password database file SEE ALSO getgrent(), netinfo.device/passwd HISTORY The functions getpwent(), getpwnam(), getpwuid(), setpwent() and endpwent() functions appeared in Version 7 AT&T UNIX. BUGS These functions leave their results in an internal static object and return a pointer to that object. Subsequent calls to these function will modify the same object. If you need re-entrant operation, you should use directly the netinfo.device. COMPATIBILITY The BSD passwd database handling routines setpwfile() and setpassent() are fairly useless in a networked environment and they are not implemented. usergroup.library/getspgrp usergroup.library/getspgrp NAME getpgrp - get process group identification SYNOPSIS #include <libraries/usergroup.h> sessionid = getpgrp() D0 pid_t getpgrp(void); FUNCTION The getpgrp() function returns the process group id for the current process. Currently, the process group ID is the same as the session ID. The 0 is valid process group ID for console session. RESULTS Upon successful completion, the value of the process group ID is returned. Otherwise, a value of -1 is returned and an error code is stored to global errno location. ERRORS [ESRCH] The calling process don't belong to any process group. SEE ALSO setsid(), exec.library/FindTask() usergroup.library/getuid usergroup.library/getuid NAME getuid, geteuid - get user process identification getgid, getegid - get group process identification SYNOPSIS ruid = getuid() D0 uid_t getuid(void); euid = geteuid() D0 uid_t geteuid(void); rgid = getgid() D0 gid_t getgid(void); egid = getegid() D0 gid_t getegid(void); FUNCTION The getuid() function returns the real user ID of the calling process, geteuid() returns the effective user ID of the calling process. The getgid() function returns the real group ID of the calling process, getegid() returns the effective group ID of the calling process. The real user ID and real group ID is specified at login time. The real ID is the ID of the user who invoked the program. As the effective user and gourp ID gives the process additional permissions during the execution of `set-user-ID' or `set-group-ID' mode programs, functions getgid() and getuid () are used to determine the real-ids of the calling process. RESULT The getuid(), geteuid(), getgid(), and getegid() functions are always successful, and no return value is reserved to indicate an error. NOTES Any task can call these functions SEE ALSO getgroups(), setuid(), setreuid(), setgid(), setregid(), setgroups() usergroup.library/getumask usergroup.library/getumask NAME getumask - get file creation mode mask SYNOPSIS #include <sys/stat.h> oldmask = getumask() D0 mode_t getumask(void); FUNCTION The getumask() routine sets the process's file mode creation mask to numask and returns the previous value of the mask. The 9 low-order access permission bits of numask are used by Unix-compatible filesystems, for examble by NFS, to turn off corresponding bits requested in file mode. RESULT The value of the file mode mask is returned by the call. ERRORS The getumask() function is always successful. SEE ALSO umask() usergroup.library/getutent usergroup.library/getutent NAME getutsid, getutent, setutent, endutent - utmp database operations SYNOPSIS #include <utmp.h> utmpent = getutsid(sid) D0 D0 struct utmp *getutsid(long); utmpent = getutent() D0 struct utmp *getutent(void); setutent() void setutent(void); endutent() void endutent(void); FUNCTION These functions operate on the utmp database. There is an utmp entry for each active session. A session is started with login command and finished with logout command. The entry returned by each reading function is defined by the structure utmp found in the include file <utmp.h>: struct utmp { long ut_time; /* the login time */ long ut_sid; /* session ID */ char ut_name[UT_NAMESIZE]; /* the login name */ char ut_line[UT_LINESIZE]; /* the name of login device */ char ut_host[UT_HOSTSIZE]; /* where the login originated */ }; The getutsid() function search the utmp database for the given session id, returning the first one encountered. The getutent() function sequentially reads the utmp database. Both functions also open the utmp database, if necessary. The setutent() function opens the utmp database. The endutent() function closes the utmp database. It is recommended to call endutent() if the program won't access utmp database any more. RESULTS The functions getutsid() and getutent() return a pointer to the utmp entry if successful; if the end of database is reached or an error occurs a null pointer is returned. The functions endutent() and setutent() have no return value. ERRORS [ENOENT] -- no utmp entries were available. SEE ALSO BUGS The getutent() and getutsid() function leave their result in an internal static object and return a pointer to that object. Subsequent calls to the same function will modify the same object. Current implementation allows only one user to be logged in concurrently. usergroup.library/initgroups usergroup.library/initgroups NAME initgroups - initialize group access list SYNOPSIS error = initgroups(name, basegid) D0 A0 D0 int initgroups(const char *, gid_t); FUNCTION The initgroups() function reads through the group file and sets up, the group access list for the user specified in name. The basegid is automatically included in the groups list. Typically this value is given as the group number from the password file. RESULT The initgroups() function returns -1 if the process has got no necessary privileges, zero if the call is succesful. FILES AmiTCP:db/group SEE ALSO setgroups() HISTORY The initgroups function appeared in 4.2BSD. usergroup.library/MU2UG usergroup.library/MU2UG NAME MU2ID - macro converting MultiUser id to usergroup id ID2MU - macro converting usergroup id to MultiUser id SYNOPSIS ug_id = MU2ID(mu_id) mu_id = ID2MU(ug_id) FUNCTION These macros are used to convert between different user ID formats. The mu_id is in the format used by MultiUser filesystem and multiuser.library. The ug_id is the format used by Unix and usergroup.library. Most of the id values are identical in usergroup.library and multiuser.library. However, these two exceptions have values as follows: usergroup.library multiuser.library super-user 0 65535 nobody -2 0 INPUTS AND RESULTS mu_id - user ID in MultiUser format. ug_id - user ID in usergroup format. BUGS The usergroup id values that won't fit into UWORD are truncated. SEE ALSO usergroup.library/setgroups usergroup.library/setgroups NAME setgroups - set group access list SYNOPSIS success = setgroups(ngroups, gidset) D0 D0 A0 int setgroups(int, const gid_t *); FUNCTION Setgroups() sets the group access list of the current user process according to the array gidset. The parameter ngroups indicates the number of entries in the array and must be no more than NGROUPS, as defined in <libraries/usergroup.h>. Only the super-user may set new groups. The super-user can not set illegal groups (-1). RESULT A 0 value is returned on success, -1 on error, with an error code stored in errno and available with ug_GetErr() function. ERRORS [EINVAL] An illegal group id was specified. [EPERM] The caller has got no necessary privileges. [EFAULT] The address specified for gidset is illegal. NOTES Any task can call this function. SEE ALSO getgroups(), initgroups() usergroup.library/setlastlog usergroup.library/setlastlog NAME setlastlog - login an user SYNOPSIS #include <utmp.h> lastlogin = setlastlog(uid, name, console, host) struct lastlog setlastlog(uid_t, char *, char *, char *); FUNCTION The setlastlog function is used to register user logging in. Each time a user is logging in, the function setlastlog() should be called to register that event. INPUTS uid -- the uid of user logging in name -- the user login name console -- the console handler name (from ug_GetConsole()) host -- the host which the user is logging in from RESULTS The setlastlog() function returns an success indicator, 0 if the call was successful, -1 otherwise. The error code is set if an error occurs. ERRORS The setlastlog() can have following error codes: [EFAULT] -- the utmp entry cannot be accessed [ENOMEM] -- the memory has been exhausted [ENOENT] -- cannot access utmp database BUGS Current implementation stores only the lastlog data of the latest user logged in. FILES SEE ALSO getutent(), getlastlog() usergroup.library/setlogin usergroup.library/setlogin NAME setlogin - set login name SYNOPSIS success = setlogin(name) D0 A1 int setlogin(const char *); FUNCTION The function setlogin() sets the login name of the user associated with the current session to name. This call is restricted to the super-user, and is normally used only when a new session is being created on behalf of the named user (for example, at login time, or when a remote shell is invoked). INPUTS name - Buffer to hold login name RESULT If a call to setlogin() succeeds, a value of 0 is returned. If setlogin() fails, a value of -1 is returned and an error code is placed into global errno location. ERRORS [EPERM] - The caller has got no necessary privileges. [EFAULT] - The name parameter gave an invalid address. [EINVAL] - The name parameter pointed to a string that was too long. Login names are limited to MAXLOGNAME (from <sys/param.h>) characters, currently 16. BUGS SEE ALSO getlogin() usergroup.library/setsid usergroup.library/setsid NAME setsid - create a new session SYNOPSIS #include <unistd.h> sessionid = setsid() D0 pid_t setsid(void); FUNCTION The setsid() function creates a new session when the calling process is not a process group leader. The calling process then becomes the session leader of this session and the only process in the new session. RESULTS Upon successful completion, the value of the new session ID is returned. Otherwise, a value of -1 is returned and an error code is stored to global errno location. ERRORS [EPERM] The calling process is already a session leader. SEE ALSO getpgrp() usergroup.library/setuid usergroup.library/setuid NAME setuid, setreuid - set real and effective user ID's setgid, setregid - set real and effective group ID's SYNOPSIS success = setuid(uid) D0 D0 int setuid(uid_t); success = setreuid(ruid, euid); D0 D0 D1 int setreuid(uid_t, uid_t); success = setgid(gid) D0 D0 int setgid(gid_t); success = setregid(ruid, euid) D0 D0 D1 int setregid(gid_t ruid, gid_t euid); FUNCTION The real and effective ID's of the current process are set according to the arguments. If ruid or euid is -1, the current uid is filled in by the system. Unprivileged users may change the real ID to the effective ID and vice-versa; only the super-user may make other changes. RETURN VALUES Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. ERRORS [EPERM] The current process is not the super-user and a change other than changing the effective id to the real id was specified. SEE ALSO getuid(), getgid(), geteuid(), getegid() NOTES Any task can call these functions. HISTORY A setuid() and setgid() function calls appeared in Version 6 AT&T UNIX. The setreuid() and setregid() function calls appeared in 4.2BSD. usergroup.library/ug_GetConsoleName usergroup.library/ug_GetConsoleName NAME ug_GetConsoleName --- Get Console Identifier SYNOPSIS name = ug_GetConsoleName(fh, buffer, size) D0 D0 A0 D1 UBYTE * ug_GetConsoleName(BPTR, UBYTE *, ULONG) FUNCTION Get a unique printable identifier for the interactive filehandle. This identifier is usually the task name of handler concatenated with message port address. INPUTS fh - An interactive filehandle buffer - Buffer to hold console identifier size - Number of bytes in buffer. RESULT name - If call is successful, pointer to buffer. NULL if error. BUGS May not get the proprer console name for all different console handlers. SEE ALSO dos.library/GetConsoleTask() usergroup.library/ug_GetErr usergroup.library/ug_GetErr NAME ug_GetErr - get current error code SYNOPSIS error = ug_GetErr(void) D0 int ug_GetErr(void) FUNCTION Most usergroup.library functions return -1 to indicate an error. When this happens (or whatever the defined error return for the routine) this routine may be called to determine more information. The default startup function will redirect the error codes also into the global variable `errno'. Note: there is no guarantee as to the value returned from ug_GetErr() after a successful operation. RESULTS error - error code SEE ALSO ug_StrError(), ug_SetupContextTags(), dos.library/IoErr() usergroup.library/ug_GetSalt usergroup.library/ug_GetSalt NAME ug_GetSalt - generate password encryption setting for an user SYNOPSIS setting = ug_GetSalt(passwd, buffer, size); D0 A0 A1 D0 UBYTE *ug_GetSalt(const struct passwd *, UBYTE *, ULONG); FUNCTION This function generates a setting parameter, which is used to configure the password encryption process. If an old entry exists, the new salt depends on it. The particular salt format depends on the system security level. INPUTS passwd - the old passwd entry for the user, or NULL if there is none. buffer - address of character array, which the new salt is stored in. size - the number of bytes in the buffer. The buffer should be at least 12 bytes long. RETURN VALUE Pointer to the buffer, or NULL if the buffer is too small. NOTE By default the Version 7 UNIX compatible setting is generated. SEE ALSO crypt() usergroup.library/ug_OnConsole usergroup.library/ug_OnConsole NAME ug_OnConsole - check whether session is on local console SYNOPSIS result = ug_OnConsole(void) D0 BOOL ug_OnConsole(void) FUNCTION Check if the user is logged on local console. RESULT result - 1 if the user is on console, 0 otherwise. BUGS Currently checking is done depending on the process window pointer. SEE ALSO usergroup.library/ug_SetupContextTags usergroup.library/ug_SetupContextTags NAME ug_SetupContextTagList - Set up the caller context ug_SetupContextTags - varargs stub for ug_SetupContextTagList SYNOPSIS success = ug_SetupContextTagList(taglist) D0 A1 ULONG ug_SetupContextTagList(struct TagItem *); success = ug_SetupContextTags(...) ULONG ug_SetupContextTags(LONG tag, ...); FUNCTION The function ug_SetupContextTags() will prepare the library caller context. INPUTS taglist - pointer to taglist Currently, there are defined tags as follows: UGT_ERRNOPTR - gives the pointer to the errno variable. The error variable is redirected to the scope of the task. If the pointer is NULL, no redirection is done anymore. UGT_ERRNOSIZE - specifies the size of the errno variable. Legal values are 1, 2 and 4. The UGT_ERRNOSIZE must be given with same call if the UGT_ERRNOPTR is given a non-NULL value. UGT_INTRMASK - specifies the interrupt signal mask. All blocking library calls will be interrrupted when a signal in the break mask is received. The signals in the `mask' are not cleared when a library call is interrupted. The signals in INTRMASK should be allocated in the context of the owning task. UGT_OWNER - changes the owner of this library instance. The UGT_OWNET tagData must be a valid task pointer or NULL. If the pointer is NULL, the library will have no owner and any task can become owner by calling ug_SetupContextTagList(UGT_OWNER, FindTask(NULL), TAG_END) ; Most of the library calls are allowed only for the owner of library. Only the owner can CloseLibrary() this library. RESULT If the call is successfull, value of 0 is returned. Otherwise the value -1 is returned. Old context is cleared, if an error occurs. The error code can be retrieved with function ug_GetErr(). ERRORS [EINVAL] An illegal input value was specified. BUGS Strange and unusual things will happen if the signal allocated for the use of the library is included in the mask. SEE ALSO ug_GetErr(), --background-- usergroup.library/ug_StrError usergroup.library/ug_StrError NAME ug_StrError - Return the text associated with error code SYNOPSIS text = ug_StrError(code) D0 D1 const char *ug_StrError(LONG); FUNCTION The strerror() function maps the error number specified by the errnum parameter to a language-dependent error message string, and returns a pointer to the string. The string pointed to by the return value should not be modified by the program, but may be overwritten by a subsequent call to this function. INPUTS code - error code returned by ug_GetErr() function. RESULT text - text associated with the error code. NOTES The current implementation will understands also the negative IO error codes. BUGS Currently only language available is English. SEE ALSO ug_GetErr() usergroup.library/umask usergroup.library/umask NAME umask - set file creation mode mask SYNOPSIS #include <sys/stat.h> oldmask = umask(newmask) D0 D0 mode_t umask(mode_t); FUNCTION The umask() routine sets the process's file mode creation mask to numask and returns the previous value of the mask. The 9 low-order access permission bits of numask are used by Unix-compatible filesystems, for examble by NFS, to turn off corresponding bits requested in file mode. This clearing allows each user to restrict the default access to his files. The default mask value is 022 (write access for owner only). Child processes should inherit the mask of the calling process. RESULT The previous value of the file mode mask is returned by the call. ERRORS The umask() function is always successful. SEE ALSO getumask()